一、应用场景
用户告警信息是提供给企业将设备异常通知至C端用户的功能。物联云平台的设备异常通知，是指设备符合平台配置的异常规则时，触发的通知功能。物联云平台在接入的设备发生异常后，可以选择是否将异常信息通知给用户。当选择将异常信息通知给用户后，用户可以通过App或其他终端查看全部异常消息通知。
- 用户查看家庭设备的异常情况。
二、功能说明
企业提供给用户查看设备异常信息时，需要先在物联云平台管理台完成异常规则配置，通过异常规则设置异常通知的发送渠道和接收人员。用户注册C端账号，并完成房屋信息认证后，即可通过App查看房屋的设备信息和异常通知。
三、前提条件
1.需要将设备接入物联云平台。
2.需要配置异常规则。
3.需要配置异常规则对应的通知方式。
四、关键流程
4.1 用户告警消息管理
流程说明：
- 首先，C端APP用户登录到物联网中台，获取到物联网中台的调用凭证以及刷新凭证。
- 其次，C端APP用户因查看告警消息列表向物联网中台发起 获取用户告警消息列表 请求，物联网中台接收到请求后，根据C端APP用户标识和消息类型过滤查找出告警消息列表返回给用户。
- 最后，C端APP用户在查看了某条告警消息后，向物联网中台发起 标记用户报警消息为已读 请求，物联网中台接收到请求后，根据告警消息标识将告警消息在持久层标记为已读。
4.2 获取用户广播消息列表
流程说明：
- 首先，C端APP用户登录到物联网中台，获取到物联网中台的调用凭证以及刷新凭证。
- 其次，C端APP用户因查看告警消息列表向物联网中台发起 获取用户广播消息列表 请求。
- 最后，物联网中台接收到请求后，根据C端APP用户标识和消息类型过滤查找出广播消息列表返回给用户。
五、API列表
5.1 用户消息
5.1.1 获取用户告警消息列表
接口描述
C端用户根据条件查询用户告警消息列表，C端App用于查看展示
请求方式
POST
请求地址
/v2/user/{user_id}/messages
请求头
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| Access-Token | true | String | 调用凭证 企业用户 |
| Content-Type | true | String | application/json |
请求参数
| 名称 | 位置 | 必填 | 类型 | 备注 |
|---|---|---|---|---|
| user_id | path | false | Int | 用户标识 |
| offset | body | false | Int | 偏移量 |
| limit | body | false | Int | 查询量 |
| sort | body | false | Object | 排序字段 |
| query | body | false | Object | 查询条件，支持操作符有 $eq：等于 $gt：大于 $lt：小于 $gte：大等于 $lte：小等于 $ne：不等于 $nin：不包含，用于数组 $in：包含，用于数组 $like：模糊匹配，用于字符串 $all：全都在，用于数组 查询字段支持id, type, notify_type, from, to, is_read, is_push,create_date |
请求示例：
{
"offset": 0,
"limit": 10,
"sort": {
"name": "desc"
},
"query": {
"id": {
"$eq": "123fedsfdsfe5w61dfds"
}
}
}返回参数说明
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| count | true | Int | 用户消息总数 |
| list | true | Array | 用户消息列表 |
| list.id | true | String | 用户消息标识 |
| list.type | true | Int | 用户消息类型，枚举 1:通知与预警 2:系统广播 3:P2P, 用户与用户 |
| list.notify_type | false | Int | 通知类型, 枚举值: 1:通知类型 2:告警类型 |
| list.from | true | String | 消息发送者标识 |
| list.to | false | Array | 消息接收者列表 |
| list.content | true | String | 消息内容 |
| list.create_date | true | String | 消息创建时间，格式如yyyy-MM-dd’T’HH:mm:ss.SS’Z’ |
| list.is_read | true | Boolean | 消息是否已读 |
| list.is_push | true | Boolean | 消息是否已发送 |
| list.alert_name | false | String | 告警消息告警规则名称 |
| list.alert_value | false | String | 告警消息告警值 |
| list.index | false | Int | 告警消息发生数据端点下标 |
返回示例：
{
"count": 1,
"list": [
{
"id": "1223sdf5ewfd1s2fdsfds56fd",
"type": 1,
"notify_type": 2,
"from": "645465632",
"to": "645465632",
"content": "南门设备掉线",
"create_date": "2019-12-16T16:00:00.000Z",
"is_read": false,
"is_push": false,
"alert_name": "设备掉线规则",
"alert_value": "1",
"index": 1
}
]
}错误码：
| 错误码 | 描述 |
|---|---|
| 4001001 | 请求数据字段验证不通过 |
| 4001002 | 请求数据必须字段不可为空 |
| 4031001 | 调用凭证权限被禁止访问 |
| 4031003 | 无效的调用凭证 |
| 4031002 | 需要调用凭证 |
| 4041001 | 接口不存在 |
| 5031001 | 系统错误 |
| 4031024 | 权限不足 |
5.1.2 标记用户报警消息为已读
接口描述
C端用户在查看自己的用户报警消息之后，将其标记为已读
请求方式
PUT
请求地址
/v2/user/{user_id}/message-read-alert
请求头
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| Access-Token | true | String | 调用凭证 企业用户 |
| Content-Type | true | String | application/json |
请求参数
| 名称 | 位置 | 必填 | 类型 | 备注 |
|---|---|---|---|---|
| user_id | path | true | Int | 用户标识 |
| type | body | true | Int | 标记类型，枚举 1:全部标记为已读 2:根据Id进行标记为已读 |
| ids | body | true | Array |
告警消息标识列表，不能超过500个 |
请求示例：
{
"type": 1,
"ids": [
"45678912sdf",
"4564498sdfs"
]
}返回参数说明
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| 无 | 无 | 无 | 无 |
返回示例：
{
}错误码：
| 错误码 | 描述 |
|---|---|
| 4001001 | 请求数据字段验证不通过 |
| 4001002 | 请求数据必须字段不可为空 |
| 4031001 | 调用凭证权限被禁止访问 |
| 4031003 | 无效的调用凭证 |
| 4031002 | 需要调用凭证 |
| 4041001 | 接口不存在 |
| 5031001 | 系统错误 |
| 4031024 | 权限不足 |
5.1.3 获取用户广播消息列表
接口描述
C端用户根据条件查询用户告警消息列表，C端App用于查看展示
请求方式
POST
请求地址
/v2/user/{user_id}/messages/broadcast
请求头
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| Access-Token | true | String | 调用凭证 企业用户 |
| Content-Type | true | String | application/json |
请求参数
| 名称 | 位置 | 必填 | 类型 | 备注 |
|---|---|---|---|---|
| user_id | path | true | Int | 用户标识 |
| offset | body | false | Int | 偏移量 |
| limit | body | false | Int | 查询量 |
| sort | body | false | Object | 排序字段 |
| query | body | false | Object | 查询条件，支持操作符有 $eq：等于 $gt：大于 $lt：小于 $gte：大等于 $lte：小等于 $ne：不等于 $nin：不包含，用于数组 $in：包含，用于数组 $like：模糊匹配，用于字符串 $all：全都在，用于数组 查询字段支持id, type, notify_type, from, to, is_read, is_push,create_date |
请求示例：
{
"offset": 0,
"limit": 10,
"sort": {
"name": "desc"
},
"query": {
"id": {
"$eq": "1235efsdfdsf5645"
}
}
}返回参数说明
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| count | true | Int | 用户消息总数 |
| list | true | Array | 用户消息列表 |
| list.id | true | String | 用户消息标识 |
| list.type | true | Int | 用户消息类型，枚举 1:通知与预警 2:系统广播 3:P2P, 用户与用户 |
| list.notify_type | false | Int | 通知类型, 枚举值: 1:通知类型 2:告警类型 |
| list.from | true | String | 消息发送者标识 |
| list.to | false | Array | 消息接收者列表 |
| list.content | true | String | 消息内容 |
| list.create_date | true | String | 消息创建时间，格式如yyyy-MM-dd’T’HH:mm:ss.SS’Z’ |
| list.is_read | true | Boolean | 消息是否已读 |
| list.broadcast | true | Object | 广播内容 |
| list.broadcast.push_id | false | String | 广播推送ID |
| list.broadcast.msg_type | false | Int | 广播消息类型 -1:未知 1:txt |
| list.broadcast.action_type | false | Int | 用户消息动作类型，枚举值: 1:点击打开页面 2:点击执行命令 3:打开应用AndroidActivity 4:打开应用 |
| list.broadcast.title | false | String | 广播推送消息标题 |
| list.broadcast.url | false | String | 当action_type等于1时, 要打开的页面地址 |
| list.broadcast.command | false | String | 当action_type等于2时, 要执行的命令 |
返回示例：
{
"count": 1,
"list": [
{
"id": "ds1611132dsfs654ds",
"type": 2,
"notify_type": 2,
"from": "565614651",
"to": "1132656523",
"content": "广播消息",
"create_date": "2019-12-16T16:00:00.000Z",
"is_read": false,
"broadcast": {
"pushId": "12356fd4ds45sdf",
"msg_type": 1,
"action_type": 1,
"title": "记得吃早餐",
"url": "http://www.baidu.com",
"command": "hello"
}
}
]
}错误码：
| 错误码 | 描述 |
|---|---|
| 4001001 | 请求数据字段验证不通过 |
| 4001002 | 请求数据必须字段不可为空 |
| 4031001 | 调用凭证权限被禁止访问 |
| 4031003 | 无效的调用凭证 |
| 4031002 | 需要调用凭证 |
| 4041001 | 接口不存在 |
| 5031001 | 系统错误 |
| 4031024 | 权限不足 |
